AI-SDLC

The problem

AI coding tools generate code. But code generation is one step in a ten-step process. What breaks in real software projects is the handoff: the planner did not communicate constraints to the coder, the reviewer missed the edge case the auditor would have caught, the documentation was never updated after the fix went in.

Agentic SDLC is built to own the whole chain. A single plain-English goal flows through six agents, each with a specific job and clear inputs and outputs. No human touches the keyboard between stages. The engine researches the codebase, plans the change, writes the code, audits it up to three times, writes the docs, and commits. The result is ready for human review and merge.

How it works: step by step

Step 1: Researcher maps the target repository using Graphify (AST-based code graph). It ingests the full codebase with Moonshot's 256K-window model (moonshot-v1-128k), identifies which files are relevant to the goal, and writes a structured context map to the Blackboard.
Step 2: Perceptor reads the Researcher's output and triages the goal: Is it a bug fix, a new feature, a refactor? What is the blast radius? It scores complexity and sets priority flags that constrain what the Architect is allowed to plan.
Step 3: Architect produces a step-by-step implementation plan: which files to touch, what functions to add or modify, what edge cases to cover. It writes this plan to the Blackboard as structured JSON that the Coder reads directly.
Step 4: Coder executes the plan. It uses kimi-k2.6 as primary (high-fidelity agentic code generation), falling over to Bedrock Qwen3-Coder, then the rest of the nine-provider chain. It writes the actual file changes and records each patch in the Blackboard.
Step 5: Auditor (up to 3 iterations) reviews the Coder's output against the original plan and a set of DNA contracts (rules about what the code must and must not do). If it finds issues, it sends the Coder back with specific instructions. After three clean passes or three audit failures, it exits the loop with a verdict.
Step 6: Documenter + auto-commit reads the final diff, updates the relevant docs and README sections, then the engine commits everything atomically with a structured commit message.

Five engineering decisions worth reading

1. Per-role model allocation

Every agent gets the model that fits its job, not a one-size-fits-all default. Researcher uses a 256K-window model because it needs to ingest a full codebase in one shot. Perceptor uses a fast 8K model because triage is cheap. Coder and Auditor use kimi-k2.6 because code generation needs the highest-fidelity reasoning available.

// From BaseAgent.js - actual production allocation
// Researcher: moonshot-v1-128k  (256K window for repo-wide ingestion)
// Perceptor:  moonshot-v1-8k    (fast triage and priority scoring)
// Architect:  moonshot-v1-8k    (rapid planning and critique)
// Coder:      kimi-k2.6         (high-fidelity agentic code generation)
// Auditor:    kimi-k2.6         (deep verification and DNA compliance)

2. MoonshotLimiter: RPM + concurrency semaphore

Moonshot's Tier 0 plan allows 20 RPM and concurrency 3. Naive clients exceed both constantly. MoonshotLimiter maintains a sliding 60-second RPM window and a concurrency semaphore. Requests queue cleanly instead of failing with 429s. This is the actual class from the source, not a diagram of one:

class MoonshotLimiter {
  constructor() {
    this.active  = 0;
    this.maxActive = 3;
    this.queue   = [];
    this.history = [];
  }
  async acquire() {
    return new Promise(resolve => {
      this.queue.push(resolve);
      this._pump();
    });
  }
  async _pump() {
    if (this.queue.length === 0 || this.active >= this.maxActive) return;
    const now = Date.now();
    this.history = this.history.filter(t => now - t < 60_000);
    if (this.history.length >= 20) {
      const delay = (this.history[0] + 60_000) - now + 100;
      setTimeout(() => this._pump(), delay);
      return;
    }
    this.active++;
    this.history.push(Date.now());
    this.queue.shift()();
  }
  release() { this.active--; this._pump(); }
}

3. Session-level circuit breaker

Once a provider exhausts every model in its chain during a run, it is skipped for the rest of the session. No wasted tokens retrying providers already known to be down. Operator manual overrides via a providerOverrides singleton let you flip a provider out of rotation without restarting the process.

4. SHA-256 response cache

The cache is keyed on SHA-256(systemPrompt + '\x00' + prompt). Exact match required, so stale results are impossible. It saves real tokens on the common retry path: the Auditor re-reviews an unchanged file, or the Researcher fetches the same query twice in one session.

function _cacheKey(sys, prompt) {
  return crypto
    .createHash('sha256')
    .update(sys + '\x00' + prompt)
    .digest('hex');
}

5. Durable Blackboard (SQLite)

All agent state lives in Blackboard.js backed by SQLite with full ACID guarantees. If the process crashes mid-pipeline, state survives. Agents never pass context through function arguments or in-memory globals - everything flows through Blackboard methods. This enforces a clean separation between agents and makes the full run observable and replayable.

Two modes

# Self-mode: operates on its own repo
node index.js --goal "add a health check endpoint"

# External mode: operates on any target project
node index.js --project /path/to/target --goal "fix the failing tests"

The same pipeline that improves AI-SDLC itself can be pointed at any other Node.js repo.

Quick start

# Repo private during beta — request access from Admin (adiyogibooks@gmail.com)
cd ai-sdlc
npm install
cp .env.example .env   # add at least one LLM API key
npm test               # 137 tests, no external services needed
node index.js --goal "add a README badge"

Ollama is always available as the local final-fallback - no API key required. If you have Ollama running at localhost:11434, the pipeline will keep working even with no cloud keys set.

The Six-Agent Pipeline